Example

- My RStudio::Conference presentation will educate attendees
  - Cover the 5 Elements of Validation
  - Be 15-20 minutes long.

Example

#' @title Specifications For RStudio Conf 2020 Success
#' @section Last updated by:
#' Ellis Hughes
#' @section Last updated date:
#' 2020/01/29

+ _Specifications_
  + 1.1 Presentation must explain validation procedure.
  + 1.2 Be entertaining by causing 3 laughter sessions.
  + 1.3 Inform and document each step necessary for success.
  + 1.4 (Optional) Fame and Glamour and start branded accessories chain.

Modular Specifications

• Single file / idea
• Easily shift and update
• De-couple Specifications

-- vignettes
    |__Validate.Rmd
    |__Validation
      |__Specifications
        |__specification_001.Rmd

Do it for your future self

• Define function requirements
• Assign Tasks

https://miro.medium.com/max/694/1*G45BFLThPqHFW9C16TNx5Q.gif

What is the purpose of this function?

foo <- function(bar,baz){
  print(bar)
  Sys.sleep(3)
  print(baz)
}

Document your code

Unit Test your code

• As the function author, does it behave as you expect

• Protection from accidental changes

• testthat

  • test expectations around your code
  • check errors are fired
  • Check outputs are consistent

Github

• Branching
• Detailed code Review
  • Style guides

Documentation

#' @title Deliver Jokes
#' @description 
#'    Deliver jokes with punchlines. Wait 3 seconds for the punchline.
#' @param Setup Joke setup
#' @param Punchline Joke punchline
#' @example
#' joke('To the person who stole my presentation -','I hope you do not Excel.')
#'      
#' @section Last updated by:
#' Ellis Hughes
#' @section Last updated date:
#' 2020/01/29

joke <- function(Setup, Punchline){
  print(Setup)
  Sys.sleep(3)
  print(Punchline)
}

Modular Function Documentation

• Track Progress
• Meet Regularly to discuss roadblocks
• Ensure high quality code

-- R
  |__jokes.R
-- man
  |__hello.Rd
-- tests
  |__testthat
  |__testthat.R

Goal

What Specifications are being satistified by the test passing

setup inputs steps to follow expectations of results

How to Document Test Cases

• Document the required data
• Record the step to run without writing the code
• Detail the expectations that need to be tested and how

Documentation

#' @title RStudio Conf 2020 Success Test Cases 001
#' @section Last updated by: 
#' Ellis Hughes
#' @section Last update date:
#' 2020/01/29

+ _Test Cases_

+ Setup: Create RStudio::Conf 2020 Presentation 
  
+ T 1.1 Test that specifications 1.2, 1.2, and 1.3 by practicing presentation on unsuspecting co-workers

  - Present to a captive audience of coworkers and later your significant other
  +  T 1.1.1 Test that the presentation was informative by asking what your audience learned.
  +  T 1.1.2 Test that you were entertaining by counting the amount of chuckles (>3)
      + T 1.1.2.1 Alternatively, groans from your significant other at your jokes (>4)

Modular Test Case Documentation

• Easily shift and update
• Easily assign Test Cases
• Track updates

-- vignettes
    |__Validate.Rmd
    |__Validation
      |__Test_Cases
        |__test_case_001.R

Benefits

• Resolves interpretation errors
  • documentation
  • test cases
• Identify improvements

Approach

• testthat format

• Combine with Roxygen comments

Documentation

context('RStudio Conf 2020 Success')

#' @title RStudio Conf 2020 Success 
#' @section Last updated by: 
#' Ellis Hughes
#' @section Last update date:
#' 2020/01/29
#' 
testthat('T1.1',{
  
  joke_result <- joke('What do you call a fake noodle?','An Impasta')
  expect_true(is_dad_joke(joke_result))
  expect_true(caused_laugher(joke_result))
  expect_true(embarrased_offspring(joke_result))
  
})

Evaluation

• testthat reporter object is created
  • success of expectations as ‘As Expected’
  • failures with the code that fails

Modular Test Code Documentation

• Easily update Test Code and expectations
• Track updates

What we have so far

• Documents for each Specification in markdown
• Roxygen documentation for Code
• Documents for Test Cases in markdown
• Test Case Code augmented with Roxygen documentation

Master Document that

• Record all elements in a single location

• Scraping for Author and Edit Dates

• Separating out specs into files allows for modular extension

• Roxygen to document editing and edit dates

• Testthat to evaluate and record test case code results

EXAMPLE OF PDF

Many thanks to all involved

• Marie Vendettuoli
• Anthony Williams
• Jimmy Fulp
• Bharathi Lakshminarayanan
• Alicia Sato
• Shannon Grant
• Paul Stutzman
• Kate Ostbye